wrapper.java.additional.12=-verbosegc:file=gc-log.txt wrapper.java.additional.13=-XX:+HeapDumpOnOutOfMemoryError wrapper.java.additional.14=-XX:HeapDumpPath=heap-dump.txt
All RHQ components, Server, Storage Node and Agent, can be installed on the supported Windows platforms. To ensure a good experience there are several things to be aware of when running on Windows. Please read through this information before proceeding with your Windows install, or upgrade.
Windows has a limited length for file paths. Unzip into a relatively short parent directory, no more than 10-15 characters, It is recommended to install under an rhq umbrella directory. So, for example:
c:/rhq
See this Microsoft MSDN article for more information.
Some 3rd party tools, like 7-Zip can avoid the issue but using a short path is the recommended approach.
A 64-Bit Java JRE or JDK is supported.
If using a 32-Bit distribution it must be a JDK (Server) distribution, not a JRE (Client) distribution. Because the 32-bit distributions still make distinction between server (JDK) and client (JRE) versions, and RHQ requires a server distribution, you must use a 32-bit JDK.
When specifying Windows paths in .properties files, or in general as part of any RHQ configuration, Values are typically treated like Java strings:
Use forward slashes where possible, especially in directory or file paths. For example: C:/rhq
If you need an explicit backslash, escape it using a double-backslash. For example: set some.property.value=foobar
RHQ 4.9 introduced the rhqctl script to control the RHQ components. On Windows, the rhqctl.bat works analogously to rhqctl on UNIX-based platforms. However, on Windows the RHQ components are installed and managed as Windows services. There are some important notes regarding Windows Services:
The Windows services run by default as the local system account (known as "Default" or ".\LocalSystem"). RHQ associates agent configuration preferences with users. Care must be taken to ensure that custom agent preferences actually get applied to the user running the RHQ Agent service. There are three options:
Install using RHQ_AGENT_RUN_AS_ME (see below) and use --agent-preference
This will run the service as the same user executing rhqctl, so the command line --agent-preference settings will apply.
Install using --agent-config <custom-agent-configuration.xml>
Without RHQ_AGENT_RUN_AS_ME the user executing rhqctl will be different that the user running the service. But with this option, RHQ will apply the custom configuration file on the initial start of the RHQ Agent.
Update the RHQ Agent configuration post-install
Without RHQ_AGENT_RUN_AS_ME the user executing rhqctl will be different that the user running the service. Without --agent-config the installed agent will have default configuration. After installation the agent config can be updated using the agent prompt commands (or direct manipulation of the registry - not recommended).
Start the command window with "Run as Administrator". This is required for manipulating Windows services (just as has been required in the past when running the RHQ Server and RHQ Agent as a service).
The Windows services run by default as the local system account (known as "Default" or ".\LocalSystem"). To install the services as a different user set the following environment variables in rhq-server-env.bat, prior to installation or upgrade:
The desired user account must have "log on as service" permission. On some Windows configurations this may need to be granted explicitly.
RHQ Server Service
RHQ_SERVER_RUN_AS=.\<username> or RHQ_SERVER_RUN_AS_ME=true
RHQ_SERVER_PASSWORD=<password>
RHQ Storage Service
RHQ_STORAGE_RUN_AS=.\<username> or RHQ_STORAGE_RUN_AS_ME=true
RHQ_STORAGE_PASSWORD=<password>
RHQ Agent Service
RHQ_AGENT_RUN_AS=.\<username> or RHQ_AGENT_RUN_AS_ME=true
RHQ_AGENT_PASSWORD=<password>
When upgrading from a version prior to those using rhqctl for installation it is possible that the RHQ_XXX_RUN_AS feature was used without also setting the RHQ_XXX_PASSWORD environment variable. It is now required to set RHQ_XXX_PASSWORD when using RHQ_XXX_RUN_AS.
This page is targeted to installs of the RHQ Server, Storage Node and Agent using rhqctl. For standalone agent installations see RHQ Agent Installation.
In general it is recommended to just run the agent as a Windows service. But if you plan to stop the service and run the agent interactively (typically this is done for development or debugging purposes) it is recommended not to install the agent service with the local system account. It will be necessary to run the agent as the same user both as the service and interactively to ensure the same agent configuration is applied in both scenarios. The agent service can be installed to run as a different user by setting the following environment variables before running "rhqctl install":
RHQ_AGENT_RUN_AS=.\<username> or RHQ_AGENT_RUN_AS_ME=true
RHQ_AGENT_PASSWORD=<password>
The RHQ Server and RHQ Agent make use of the temporary directory set as java.io.tmpdir. On Windows this is typically located under %USERPROFILE%/AppData/Local/Temp. This directory must exist and be accessible to the user account running the RHQ components, typically the account assigned to running the services, or at times, the account running the component in a console.
If the directory is not accessible RHQ will log a warning and then attempt to create and use <InstallDir>/temp.
When using a 32-bit Java distribution, and the default Local System account to run the RHQ Windows service, the java.io.tmpdir account will not be accessible. This is a known Windows issue and not due to RHQ. In this case RHQ will create its own temp directory as described above. To avoid this do not use the default Local System account, or install a 64-bit version of the Java Service Wrapper (not provided with RHQ), or override the setting of java.io.tmpdir.
To use a non-default temp directory for an RHQ component on Windows edit the Java Service Wrapper include file. See Overriding Properties in the Java Service Wrapper for details. For example, for the RHQ Server this would be <InstallDir>/bin/wrapper/rhq-server-wrapper.inc. Follow the inline instructions for setting java.io.tmpdir, or any other Java property that you may want to set.
Note that to update the wrapper configuration you should first install the RHQ Agent, then edit the configuration, then start the RHQ Agent.
Note that at this writing the RHQ Storage Node does not utilize java.io.tmpdir.
Once installed the RHQ Windows service is configured by the service wrapper configuration file, located at <install-dir>\bin\wrapper\rhq-xxx-wrapper.conf. This file sets some of the Java Service Wrapper configuration settings. Before editing this file, refer to the Java Service Wrapper's property configuration documentation located at http://wrapper.tanukisoftware.org/doc/english/properties.html. Editing this file is not usually necessary. More common will be adding or overriding properties in <install-dir>\bin\wrapper\rhq-xxx-wrapper.conf.
RHQ Windows services are configured via the service wrapper configuration files found in bin/wrapper. The standard settings are in the rhq-xxx-wrapper.conf file. That file can be edited but the recommended approach is to override and add properties in the rhq-xxx-wrapper.inc file. To override or add properties follow the inline instructions for adding "wrapper.java.additional.N" lines. For example:
wrapper.java.additional.12=-verbosegc:file=gc-log.txt wrapper.java.additional.13=-XX:+HeapDumpOnOutOfMemoryError wrapper.java.additional.14=-XX:HeapDumpPath=heap-dump.txt
Make sure the numbering is correct. The first property in the .inc file must increment from the last property in the .conf file.
To remove services use rhqctl. For example: "rhqctl remove". Note that removing Windows services does not uninstall the RHQ component. In general it should not be necessary to remove the Windows services but if done the "rhqctl install" command will recreate the service even if the component is already installed.
See RHQ Browsers for information on browser support, including IE versions.
More Windows related information may be contained in the RHQ FAQ.